9.4 Searching Sequences

These functions search for elements or subsequences in a sequence. (See also cl-member and cl-assoc; see Lists.)

Function: cl-find item seq &key :test :test-not :key :start :end :from-end

This function searches seq for an element matching item. If it finds a match, it returns the matching element. Otherwise, it returns nil. It returns the leftmost match, unless :from-end is true, in which case it returns the rightmost match. The :start and :end arguments may be used to limit the range of elements that are searched.

Function: cl-position item seq &key :test :test-not :key :start :end :from-end

This function is like cl-find, except that it returns the integer position in the sequence of the matching item rather than the item itself. The position is relative to the start of the sequence as a whole, even if :start is non-zero. The function returns nil if no matching element was found.

Function: cl-count item seq &key :test :test-not :key :start :end

This function returns the number of elements of seq which match item. The result is always a nonnegative integer.

The cl-find-if, cl-find-if-not, cl-position-if, cl-position-if-not, cl-count-if, and cl-count-if-not functions are defined similarly.

Function: cl-mismatch seq1 seq2 &key :test :test-not :key :start1 :end1 :start2 :end2 :from-end

This function compares the specified parts of seq1 and seq2. If they are the same length and the corresponding elements match (according to :test, :test-not, and :key), the function returns nil. If there is a mismatch, the function returns the index (relative to seq1) of the first mismatching element. This will be the leftmost pair of elements that do not match, or the position at which the shorter of the two otherwise-matching sequences runs out.

If :from-end is true, then the elements are compared from right to left starting at (1- end1) and (1- end2). If the sequences differ, then one plus the index of the rightmost difference (relative to seq1) is returned.

An interesting example is (cl-mismatch str1 str2 :key 'upcase), which compares two strings case-insensitively.

Function: cl-search seq1 seq2 &key :test :test-not :key :from-end :start1 :end1 :start2 :end2

This function searches seq2 for a subsequence that matches seq1 (or part of it specified by :start1 and :end1). Only matches that fall entirely within the region defined by :start2 and :end2 will be considered. The return value is the index of the leftmost element of the leftmost match, relative to the start of seq2, or nil if no matches were found. If :from-end is true, the function finds the rightmost matching subsequence.